Skip to content

fix: add Vercel deploy config and workflow for docs site#1739

Open
MeGaurav4 wants to merge 1 commit into
headroomlabs-ai:mainfrom
MeGaurav4:fix/vercel-docs-deploy-1730
Open

fix: add Vercel deploy config and workflow for docs site#1739
MeGaurav4 wants to merge 1 commit into
headroomlabs-ai:mainfrom
MeGaurav4:fix/vercel-docs-deploy-1730

Conversation

@MeGaurav4

@MeGaurav4 MeGaurav4 commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown

Description

The Vercel docs site at headroom-docs.vercel.app had no automated deployment pipeline, so newly added pages (persistent-installs, savings) return 404 despite existing in the repo and building correctly locally.

Closes #1730

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking function added)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Performance improvement
  • Code refactoring (no functional changes)

Changes Made

  • Add docs/vercel.json with explicit Next.js project config (framework, build/install commands)
  • Add deploy-vercel job to .github/workflows/docs.yml to auto-deploy on pushes to main touching docs/**

Testing

  • Unit tests pass (pytest)
  • Linting passes (ruff check .)
  • Type checking passes (mypy headroom)
  • New tests added for new functionality
  • Manual testing performed

Test Output

Local build verification:
cd docs && npm ci && npm run build
Build succeeded - persistent-installs and savings pages

Real Behavior Proof

  • Environment: Linux x86_64, Node.js 20
  • Observed result: Both pages build and render correctly locally
  • Not tested: Live Vercel deployment (requires maintainer secrets)

Review Readiness

  • I have performed a self-review
  • This PR is ready for human review

Additional Notes

Requires three repo secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.

@MeGaurav4
fix: add Vercel deploy config and workflow for docs site
b941a0f 
The Vercel docs site at headroom-docs.vercel.app had no automated
deployment pipeline, so newly added pages (persistent-installs,
savings) return 404 despite existing in the repo and building
correctly locally.

- Add docs/vercel.json with explicit Next.js project config
- Add deploy-vercel job to docs.yml to auto-deploy on pushes
  to main touching docs/

Closes headroomlabs-ai#1730
@github-actions

github-actions Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

PR governance

This PR does not yet satisfy the required template fields:

  • Fill in Real Behavior Proof → Exact command / steps.

Please update the PR body, or move the PR back to draft while it is still in progress.

@github-actions github-actions Bot added the status: needs author action Pull request body or readiness checklist still needs author updates label Jul 3, 2026
JerrettDavis
JerrettDavis requested changes Jul 3, 2026
View reviewed changes

@JerrettDavis JerrettDavis left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs one deployment-shape fix before it is safe to merge.

The new job runs npx vercel deploy --prod with working-directory: docs, and docs/vercel.json tells Vercel to install/build that project. But docs/package.json depends on the local TypeScript SDK as "headroom-ai": "file:../sdk/typescript", and docs/package-lock.json records that as a link to ../sdk/typescript. If the Vercel project upload/build root is docs, that parent directory is outside the deployment context, so the remote install/build can fail even though cd docs && npm ci && npm run build works in a full local checkout.

Please adjust the workflow/config so the Vercel deployment has access to the monorepo dependency it needs. For example, deploy with the repository root as the uploaded context while configuring the Vercel project/root directory as docs, or change the docs dependency/build path so it does not rely on ../sdk/typescript during Vercel’s remote install. Once that is fixed, the workflow should also validate the same Next/Fumadocs build path it deploys, not only the legacy mkdocs job.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JerrettDavis JerrettDavis JerrettDavis requested changes
@chopratejas chopratejas Awaiting requested review from chopratejas chopratejas is a code owner
@DevanshiVyas DevanshiVyas Awaiting requested review from DevanshiVyas DevanshiVyas is a code owner

Assignees

No one assigned

Labels

status: needs author action Pull request body or readiness checklist still needs author updates

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[BUG] Vercel docs site stale (404 for /docs/persistent-installs and /docs/savings)

2 participants

@MeGaurav4 @JerrettDavis